Yonin No Translators
Email :yoninnotranslators@hotmail.com
Web   :ynt.Darkmazda.com

-----------------------------------------------------------
SNES Trace File editor Instruction File
Revised Last : 11/08/2005
-----------------------------------------------------------

==============================================================================================================
!Please note the following!

  Use at your OWN risk!
  YnT and Associates can NOT be held responsable for any damage caused by this software.
  YnT guarantees that it is 100% Virus-free, but for your safety, before using it, we suggest you 
  scan the files properly.
  This software is free of any fee. Its pure hobby, and thus 100% non - profit oriented and non-commercial.
  SNES, Nintendo, are (C) of theyr respective Companies. Ynt is not affilited with any of them in any way.

==============================================================================================================

Bug Report
===============

  Please report any bug you find to the following email address : yoninnotranslators@hotmail.com
  with an exaurient explanation of the error that occoured during the usage, and a screenshot of the 
  error itself.

What is this?
===============

  This is a nice utility to use in conjunction with trace logs. It enables you to map addresses, 
  define offset labels, scopes and variables. As for the moment, it supports LT's SNES9x trace files
  and Geiger's SNES9x debugger trace files. It's intented to improve navigation, modifying of trace
  files and realize the possibility to map address locations.

Installing notes
===============

1 Extract the whole archive content to any directory.
2 Check that all needed files are present. 
  WARNINIG : The tool will work 100% correctly only on "fresh" and out-of-the-tracer generated files!!!
  It MAY work on partially edited files, but that's not guaranted.
3 Launch the Editor.

Functionality
===============

  It enables you to edit and define scopes, variables and labels on any imported trace file.
  Here a list of the menu entries and a brief explanation of theyr functionality :

  a) File 
	1)New
		Creates a new project from scratch.
		You'll have to choose from one of the available recognized trace log formats, ONLY.
		Sorry guys, but compatibility will improve in future.
		Once you select the trace file you want to work on, you'll need to define a map file.
		That's where the whole mappings will be stored. Beware, only the scope and variable
		definitions will be saved in this file. The labels will be defined in a file apart.
		You can use exiting map files, so that you can start your work from there. Once it finishes
		to load the trace file, and that can take a VERY LONG TIME, depending from the size of
		the log file, you'lll see the main screen.
	2)Open Project
		Opens an existing project.
	3)Open Log File
		Opens a single converted log file IN AN ALREADY OPENED PROJECT only! That is to make the switching of
		more log files in a single project possible.
	4)Import Log File
		Imports a true original format (LT or Geiger format) log file in the current project. 
	5)Close Log File
		Closes the current log file ONLY, not the project itself.
	6)Close project
		Closes the whole project.
	7)Save project as..
		As the name says.
	8)Save project
		As the name says.
	9)Save log file
		As the name says.
	10)Save log file as...
		As the name says.
	11)Exit
		As the name says.
  b)Edit
	Cut, copy and paste functions.
  c)Actions
	1)Search 
		Various search options (WARNING : BUGGY!)
	2)Bookmarks
		Tools for bookmarks defining
	3)Exports - TO BE DONE IN FUTURE VERSIONS
	4)Options - various options (WARNING : NOT FINISHED AND PRETTY USELESS)
  d)Help
	1)About - About window

How the heck do I use this tool????
=======================================

  Ok, and now for the hot part.
  Once you got (probably) your trace file loaded, you see it as a tree on the left of the window.
  On the right you have the following sections :
  a) CPU status (of every single line, changes when you navigate from one to another (no really??))
  b) Mappings, Labels, Code cache sections
    Here's the hearth of the tool.
    Mappings section :
      You can define scopes to which you can add mappings for memory addresses(aka names for variables)
      The default scope is the "global" scope (obvious). You can assign "lines" (read offsets) to a scope 
      by selecting them and pressing Ctrl-F1.
      After that, you can create mappings for the scope you just created. For example, you can assign the
      name "test" to address location $0000A1. And, for the magic of my power, all $0000A1 will appear as
      "test" in the scope the mapping you just defined belongs to. That's it for the Mappings section.
    Labels section :
      Pretty obvious. Here you have only one scope, of course. Labels are just "labels" for determinated
      offsets. That's all. They are very good to increase readability of branches, jumps, subroutines etc.
    Code cache section:
      The most interesting part of the whole : its still not perfect, and very ambitious, but its pointing
      the right way - its basical concept is to reuse the structure of the code it holds to quickly sort 
      out lines from newly imported trace files, setting mappins and scopes on the fly. Nifty, huh?
      So if you drag some routine lines from the code tree to the code cache, maybe with a scope defined,
      and some mappings too, and you close the current log file you are using and import another,
      it _should_ alreadyset up the (in the trace file present) lines following the structure it sees in
      the code cache.
  c)Line Comments
      A simply place where you can put sentences like "satsu 4m l33t" or whatever in it. Beware, to confirm 
      changes you HAVE to press the saving button that's beneath it.

Ok, i think im getting it..what else do i have to know?
=========================================================
   There's some quick navigation functions when you right-click the code tree too.
   Here some explanations of the most obscure ones :
	Goto Start node : navigates to the first line of the trace file. Which, obviously, doesn't have to
 				coincide with the first line you see in the trace file.
        Goto target offset : usefull to quickly navigate to branch/routine/jump targets.
   There's two buttons for navigating back and forth in step sequence you had the tree too. Guess how they
   look like?

Great!I can't wait to use it! Did you tell me everything i need to know?
==========================================================================
   Actually, no. There's another nifty function that helps you keep overview of the trace file.
   If you select a line that has a target offset, as for example "LDA $A1", and you press the Ctrl-Space
   combination, a (oh wow!) slide control will show up, showing all other locations (read rom offsets)
   on wich the same memory location is accessed. By clicking on one of them you'll quickly navigate to 
   the selected spot.    

Things to do better (=TODO's)
==============================================
-Speed up trace file importing, and speed in general!
-Fix bugs
-Add export functions
-Improve the code cache functionalities and kill the last bugs
-Fix bugs


Ver 1.0 Beta
  First release
-----------------------------------------------------..-------------------------------------------------------

TRACE LOGGER PROJECT
------------------------------------------------
Mantained  by
  YnT

Main coder
  Kammedo

Special Thanks
===============

  Byuu - Sometimes still wondering if you're alive, somewhere, dreaming about BL maybe. Wish you lots of fun ^^
  TruPlaya - If it wasn't for you, my journey in the world of Emulation (and in ASM coding at all) would never had started.
             Thanks alot! ^^
  Neill Corlett - SD3 am woah
  DarkForce - One of the best hackers out there, if not the God on Emu itself.
  Matthias Call - you showed me the way life is. Thanks alot. I hope you'll have a nice beer wherever you are.
  All the people of "da scene", Thanks for supporting me during my illness. It counted really much to me. Thanks guys.
  y0shi, qwerty - for theyr great SNES docs.
